<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.7: http://docutils.sourceforge.net/" />
<title>Goblin Camp build system reference</title>
<style type="text/css">

/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 6253 2010-03-02 00:24:53Z milde $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin: 0 0 0.5em 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left, .figure.align-left, object.align-left {
  clear: left ;
  float: left ;
  margin-right: 1em }

img.align-right, .figure.align-right, object.align-right {
  clear: right ;
  float: right ;
  margin-left: 1em }

img.align-center, .figure.align-center, object.align-center {
  display: block;
  margin-left: auto;
  margin-right: auto;
}

.align-left {
  text-align: left }

.align-center {
  clear: both ;
  text-align: center }

.align-right {
  text-align: right }

/* reset inner alignment in figures */
div.align-right {
  text-align: left }

/* div.align-center * { */
/*   text-align: left } */

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font: inherit }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="goblin-camp-build-system-reference">
<h1 class="title">Goblin Camp build system reference</h1>

<p>This document describes third iteration of the Goblin Camp build system, and replaces
earlier <tt class="docutils literal">build/README.rst</tt>.</p>
<!-- This is reStructuredText document. You can build HTML version using rst2html utility -->
<!-- bundled with docutils (http://docutils.sourceforge.net). -->
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#frequently-encountered-problems" id="id1">Frequently encountered problems</a></li>
<li><a class="reference internal" href="#required-tools-and-libraries" id="id2">Required tools and libraries</a></li>
<li><a class="reference internal" href="#configuring-the-build-configuration-file-and-features" id="id3">Configuring the build — configuration file and features</a><ul>
<li><a class="reference internal" href="#configuring-libpng" id="id4">Configuring libpng</a></li>
<li><a class="reference internal" href="#configuring-opengl" id="id5">Configuring OpenGL</a></li>
<li><a class="reference internal" href="#configuring-python" id="id6">Configuring Python</a></li>
<li><a class="reference internal" href="#configuring-sdl" id="id7">Configuring SDL</a></li>
<li><a class="reference internal" href="#configuring-windows-sdk" id="id8">Configuring Windows SDK</a></li>
<li><a class="reference internal" href="#configuring-zlib" id="id9">Configuring zlib</a></li>
<li><a class="reference internal" href="#configuring-goblin-camp-features" id="id10">Configuring Goblin Camp — features</a></li>
</ul>
</li>
<li><a class="reference internal" href="#using-the-build-system" id="id11">Using the build system</a></li>
<li><a class="reference internal" href="#using-additional-tools" id="id12">Using additional tools</a></li>
</ul>
</div>
<div class="section" id="frequently-encountered-problems">
<h1><a class="toc-backref" href="#id1">Frequently encountered problems</a></h1>
<ul class="simple">
<li>Paths used in configuration file should always use slashes, not backslashes (even on Windows).</li>
<li>Library names should not include <tt class="docutils literal">lib</tt> prefix when using GCC.</li>
</ul>
</div>
<div class="section" id="required-tools-and-libraries">
<h1><a class="toc-backref" href="#id2">Required tools and libraries</a></h1>
<p>Goblin Camp, as any non-trivial piece of software, depends on several tools and external libraries.
To build it, you will need:</p>
<ul class="simple">
<li>A <strong>working C++ compiler</strong>. We support MSVC2010 on Windows, and GCC on Linux and OSX. Codebase is
guaranteed to build at least on Windows, and tested quite often on Linux. Other compilers and
operating systems are not supported (and also configurations like building on Linux using winelib).
Clang compiler should be able to build the codebase, but has not been tested yet. Cross-compiling is
not yet supported reliably.</li>
<li><a class="reference external" href="http://sourceforge.net/projects/boost/files/boost-jam/3.1.18/">BJam</a> <strong>03.1.18</strong> or newer. Build system is based on Boost.Build, which in turn is built on top
of the BJam.</li>
<li><a class="reference external" href="http://python.org">Python</a> <strong>2.7</strong> — there are few Python scripts used in the process of building Goblin Camp, so you
will need a working installation. Python is also used as a scripting engine in the game, so you
will also need a linkable library (either debug or release version). Neither Python 3.x nor older
versions of 2.x line are suitable to be used with Goblin Camp at the moment.</li>
<li><a class="reference external" href="http://libsdl.org">SDL</a> <strong>1.2</strong> and <a class="reference external" href="http://www.libsdl.org/projects/SDL_image/">SDL_image</a> <strong>1.2</strong>.</li>
<li><a class="reference external" href="http://libpng.org/pub/png/libpng.html">libpng</a> — both 1.2 and 1.4 should work, but <strong>1.4</strong> is proven to work and recommended.</li>
<li><a class="reference external" href="http://zlib.net">zlib</a> — you should try to always use the latest version (<strong>1.2.5</strong> at the time of writing this document).</li>
<li>If you're building the Windows version — <a class="reference external" href="http://microsoft.com/downloads/details.aspx?FamilyID=6b6c21d2-2006-4afa-9702-529fa782d63b">Windows SDK</a> <strong>7</strong> (either 7.0 bundled with MSVC2010 or 7.1),
and while older are not tested against, they should work as well (Goblin Camp is targetting WinXP SP2 and newer).</li>
<li>If you're building the Linux version — GLX (libGL; or another compatible OpenGL implementation).</li>
</ul>
<p>Goblin Camp also depends on Boost and libtcod, but those are bundled with the sources,
and built automatically along with the game (you can find them in the <tt class="docutils literal">vendor</tt> subdirectory).</p>
</div>
<div class="section" id="configuring-the-build-configuration-file-and-features">
<h1><a class="toc-backref" href="#id3">Configuring the build — configuration file and features</a></h1>
<p>If your libraries live in non-standard location (e.g. outside paths specified in INCLUDE/LIB
environment variables for MSVC2010), you will need to create a configuration file for the build.
In this file you can also fine-tune compiler settings (e.g. tell the build system to use specific
executable, or specific flags). Configuration file is typically named <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> (Boost.Build
will look for one in your home directory), but I recommend naming it differently, e.g. <tt class="docutils literal"><span class="pre">gc-config.jam</span></tt>.</p>
<p>Minimal configuration file should at least specify which compiler is to be used, one of:</p>
<pre class="literal-block">
using msvc ;
using gcc ;
using darwin ;
using clang ;
</pre>
<p>To learn what additional options can be specified for the compiler, see <a class="reference external" href="http://boost.org/doc/tools/build/doc/html/bbv2/reference/tools.html">this document</a>.</p>
<p>To configure a library you use:</p>
<pre class="literal-block">
using library : properties ;
</pre>
<p>The order of the <tt class="docutils literal">using</tt> directives does not matter.</p>
<div class="section" id="configuring-libpng">
<h2><a class="toc-backref" href="#id4">Configuring libpng</a></h2>
<p>Tool name: <tt class="docutils literal">libpng</tt>.</p>
<p>Available properties:</p>
<ul class="simple">
<li><tt class="docutils literal">&lt;library&gt;path</tt> — path to the library</li>
<li><tt class="docutils literal">&lt;include&gt;path</tt> — path to the headers</li>
<li><tt class="docutils literal">&lt;name&gt;library</tt> — name of the library (default is <tt class="docutils literal">libpng</tt>)</li>
</ul>
<p>Example:</p>
<pre class="literal-block">
using libpng : &lt;library&gt;C:/dev/libs/msvc10-x86/lib &lt;include&gt;C:/dev/libs/msvc10-x86/include &lt;name&gt;lpng14 ;
</pre>
</div>
<div class="section" id="configuring-opengl">
<h2><a class="toc-backref" href="#id5">Configuring OpenGL</a></h2>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This tool is relevant only on *nix systems, and ignored on Windows (as OpenGL libraries are part of the Windows SDK).</p>
</div>
<p>Tool name:: <tt class="docutils literal">opengl</tt>.</p>
<p>Available properties:</p>
<ul class="simple">
<li><tt class="docutils literal">&lt;library&gt;path</tt> — path to the library</li>
<li><tt class="docutils literal">&lt;include&gt;path</tt> — path to the headers</li>
<li><tt class="docutils literal">&lt;name&gt;library</tt> — name of the library (default is <tt class="docutils literal">GL</tt>)</li>
</ul>
<p>Example:</p>
<pre class="literal-block">
using opengl : &lt;name&gt;GL &lt;include&gt;/usr/local/include &lt;library&gt;/usr/local/lib ;
</pre>
</div>
<div class="section" id="configuring-python">
<h2><a class="toc-backref" href="#id6">Configuring Python</a></h2>
<p>Tool name: <tt class="docutils literal">python</tt>.</p>
<p>Available properties:</p>
<ul class="simple">
<li><tt class="docutils literal">&lt;library&gt;path</tt> — path to the library</li>
<li><tt class="docutils literal">&lt;include&gt;path</tt> — path to the headers</li>
<li><tt class="docutils literal">&lt;name&gt;library</tt> — name of the library (NB: <tt class="docutils literal">&lt;debug&gt;yes</tt> will not modify the name, you need to specify it explicitly) — default is <tt class="docutils literal">python27</tt></li>
<li><tt class="docutils literal">&lt;exec&gt;path</tt>    — path to the interpreter executable</li>
<li><tt class="docutils literal">&lt;debug&gt;yes</tt>    — whether debug version of the library is being used (typically named pythonXX_d)</li>
</ul>
<p>Example:</p>
<pre class="literal-block">
using python : &lt;library&gt;C:/dev/apps/Python27/libs &lt;include&gt;C:/dev/apps/Python27/include &lt;exec&gt;C:/dev/apps/Python27/python.exe &lt;name&gt;python27 ;
</pre>
</div>
<div class="section" id="configuring-sdl">
<h2><a class="toc-backref" href="#id7">Configuring SDL</a></h2>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This tool handles both SDL and SDL_image.</p>
</div>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">We're currently assuming SDL.h file is directly in the search path (i.e. not in
the SDL subdirectory).</p>
</div>
<p>Tool name: <tt class="docutils literal">sdl</tt>.</p>
<p>Available properties:</p>
<ul class="simple">
<li><tt class="docutils literal">&lt;library&gt;path</tt> — path to the libraries</li>
<li><tt class="docutils literal">&lt;include&gt;path</tt> — path to the headers</li>
</ul>
<p>Example:</p>
<pre class="literal-block">
using sdl : &lt;library&gt;C:/dev/libs/msvc10-x86/lib &lt;include&gt;C:/dev/libs/msvc10-x86/include/SDL ;
</pre>
</div>
<div class="section" id="configuring-windows-sdk">
<h2><a class="toc-backref" href="#id8">Configuring Windows SDK</a></h2>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This tool is (obviously) used only on Windows.</p>
</div>
<p>Tool name: <tt class="docutils literal">winsdk</tt>.</p>
<p>Available properties:</p>
<ul class="simple">
<li><tt class="docutils literal">&lt;library&gt;path</tt> — path to the libraries</li>
<li><tt class="docutils literal">&lt;include&gt;path</tt> — path to the headers</li>
</ul>
<p>Example:</p>
<pre class="literal-block">
using winsdk : &lt;library&gt;C:/dev/libs/WinSDK/v7.1/Lib &lt;include&gt;C:/dev/libs/WinSDK/v7.1/Include ;
</pre>
</div>
<div class="section" id="configuring-zlib">
<h2><a class="toc-backref" href="#id9">Configuring zlib</a></h2>
<p>Tool name: <tt class="docutils literal">zlib</tt>.</p>
<p>Available properties:</p>
<ul class="simple">
<li><tt class="docutils literal">&lt;library&gt;path</tt> — path to the library</li>
<li><tt class="docutils literal">&lt;include&gt;path</tt> — path to the headers</li>
<li><tt class="docutils literal">&lt;name&gt;library</tt> — name of the library (default is <tt class="docutils literal">zdll</tt> on Windows and <tt class="docutils literal">z</tt> on other OSes)</li>
</ul>
<p>Example:</p>
<pre class="literal-block">
using zlib : &lt;library&gt;C:/dev/libs/msvc10-x86/lib &lt;include&gt;C:/dev/libs/msvc10-x86/include &lt;name&gt;zdll ;
</pre>
</div>
<div class="section" id="configuring-goblin-camp-features">
<h2><a class="toc-backref" href="#id10">Configuring Goblin Camp — features</a></h2>
<p>There are several aspects of the build that are tunable through so-called features,
which are passed on the command line as <tt class="docutils literal">feature=value</tt>.</p>
<p>Available features:</p>
<ul class="simple">
<li><tt class="docutils literal">variant</tt> — possible values are either <tt class="docutils literal">debug</tt> or <tt class="docutils literal">release</tt>. Debug builds are slow
(no optimisations), but fast to build and debugging-friendly. Release builds are heavily optimised,
but may be much slower to build and harder to debug. You can use <tt class="docutils literal">variant=debug,release</tt> to build
both variants simultaneously (although that's not very useful).</li>
<li><tt class="docutils literal"><span class="pre">address-model</span></tt> — possible values are either <tt class="docutils literal">32</tt> or <tt class="docutils literal">64</tt>. Specifies whether compiler
should generate 32- or 64-bit code. Remember that architecture of the dependencies must match this
setting (you <strong>cannot</strong> link 32-bit code with 64-bit libs or 64-bit code with 32-bit libs)!
You can use <tt class="docutils literal"><span class="pre">address-model=32,64</span></tt> to build both versions simultaneously, but currently it'll
probably fail at linking (since you can only configure only one search path for libraries).</li>
<li><tt class="docutils literal">link</tt> — possible values are either <tt class="docutils literal">shared</tt> or <tt class="docutils literal">static</tt>. Tells the build system whether
it should try to link the resulting binary dynamically or statically. This is more of a hint,
and may not change much.</li>
<li><tt class="docutils literal"><span class="pre">runtime-link</span></tt> — possible values are either <tt class="docutils literal">shared</tt> or <tt class="docutils literal">static</tt>. Tells the build system
whether it should link the C/C++ runtime libraries statically or dynamically. Note that setting
this to <tt class="docutils literal">static</tt> is generally a bad idea, and is strongly discouraged.</li>
</ul>
</div>
</div>
<div class="section" id="using-the-build-system">
<h1><a class="toc-backref" href="#id11">Using the build system</a></h1>
<p>To trigger the build, run <tt class="docutils literal">bjam</tt> with appropriate parameters:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">--user-config=file</span></tt> — specifies user config to use. See <a class="reference internal" href="#configuring-the-build-configuration-file-and-features">Configuring the build — configuration file and features</a></li>
<li><tt class="docutils literal"><span class="pre">-jN</span></tt> — specifies the number of parallel compiler processes to use. Recommended setting is at least 2, and more on multicore machines</li>
<li><tt class="docutils literal"><span class="pre">-a</span></tt> — tells bjam to rebuild entire project and all of its children</li>
<li><tt class="docutils literal"><span class="pre">-tX</span></tt> — rebuilds target <tt class="docutils literal">X</tt></li>
<li><tt class="docutils literal"><span class="pre">--clean</span></tt> — purges build cache (<tt class="docutils literal">build/tmp</tt> directory)</li>
</ul>
<p>To (re-)build only specific part of the codebase (e.g. to rebuild Goblin Camp without rebuilding vendor projects), change directory
to project's (i.e. from the one containing Jamroot to the one containing Jamfile) and then run invoke bjam. Note that dependencies
will be built automatically, even if you trigger the build of only one project.</p>
<p>After the build, you will find Goblin Camp executables in the <tt class="docutils literal"><span class="pre">build/bin-*-*</span></tt> directory (actual name depends
on the variant and target address model of the build).</p>
</div>
<div class="section" id="using-additional-tools">
<h1><a class="toc-backref" href="#id12">Using additional tools</a></h1>
<p>There are several tools bundled with the Goblin Camp, all in <tt class="docutils literal">tools</tt> subdirectory:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">bundle-boost.py</span></tt> copies Boost headers used by the game into vendor directory</li>
<li><tt class="docutils literal"><span class="pre">gather-dlls.py</span></tt> analyses the executable and looks for DLLs it depends on</li>
<li><tt class="docutils literal"><span class="pre">generate-solution.py</span></tt> generates MS Visual Studio 2010 solution and project for the Goblin Camp
(it will be put into <tt class="docutils literal">Goblin Camp</tt> subdirectory, and will run bjam to do the build)</li>
<li><tt class="docutils literal"><span class="pre">make-installer.py</span></tt> creates NSIS installer out of release build</li>
</ul>
</div>
</div>
</body>
</html>
